home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 2 / MacMania 2.toast / Art⁄Graphics / PvRay05d1 Folder / PVRAY05 < prev    next >
Encoding:
Text File  |  1992-05-24  |  16.2 KB  |  371 lines  |  [TEXT/ttxt]
  1.    Persistence of Vision Raytracer 
  2.    Version 0.5 ß Documentation
  3. -----------------------------------------
  4.  
  5. For general documentation see PVDOX.CPT.
  6. These docs are fairly sparse this time around. We're working on better
  7. ones now.
  8.  
  9. This is a BETA version, so please keep those bug reports comin'! 
  10.  
  11.  INTERPOLATE keyword added for bump and image maps.
  12.  Syntax: interpolate 2 or interpolate 4
  13.          2 == Bilinear Interpolation
  14.          4 == Normalized Distance Interpolation
  15.  USE_COLOUR keyword added for maps.
  16.  USE_INDEX keyowrd added for maps.
  17.  END_MAP keyword added for maps.
  18.  
  19.  IMPORTANT Case sensitivity 
  20.  --------------------------
  21.   Case sensitive keywords and command line option added.
  22.    > case_sensitive_yes -- All words checked for exact case. Keywords must be in upper case. (*Old DKB Style*)
  23.  > case_sensitive_no  -- Case is ignored for all words.
  24.  > case_sensitive_opt -- DEFAULT - All words checked for exact case except
  25. keywords. Keywords will be accepted in upper and/or lower case. 
  26.  - The declared colors Red, Green, and Blue in colors.dat are now CRed, CBlue,
  27.  CGreen.
  28.  - The texture Sky is now Blue_Sky
  29.  
  30. COMMAND LINE Options  
  31.  --------------------  
  32.  > Case sensitivity -- /ty = yes, /tn = no, /to = opt (see above)
  33.  
  34.  +vO will enable old style terse verbose, line number only.
  35.  +v0 will enable old new style verbose.
  36.  +v1 (default) will enable new improved style verbose.
  37.  
  38.  
  39.  New IBM-PC display options
  40.  --------------------------
  41.  +dxy enables display adapter type x, with palette option y.
  42.  
  43.    Supported Display Adapter Types:
  44.  
  45.      0 - (default) Autodetect display adapter from types below:
  46.      1 - Basic, Plain Vanilla VGA 320x200
  47.      2 - MVGA (Mode 13X) Tweaked VGA 360x480 (if > 320x200)
  48.      3 - Tseng Labs 3000 SVGA 640x350, 640x480, 800x600
  49.      4 - Tseng Labs 4000 SVGA 640x350, 640x400, 640x480, 800x600,                  1024x768
  50.      5 - AT&T VDC600 SVGA 640x400 (with cheesy autodetect)
  51.      6 - Oak Technologies OTI-067 SVGA 640x480
  52.      7 - Video 7 SVGA, VRAM FastRAM 640x480
  53.      8 - Video 7 Vega VGA, Cirrus Chip (uses Mode 1 or 2 above)
  54.      9 - Paradise SVGA 640x480
  55.      A - Ahead Systems Version A SVGA 640x480
  56.      B - Ahead Systems Version B SVGA 640x480
  57.      C - Chips And Technologies SVGA 640x480
  58.      D - ATI VGA Wonder 640x480
  59.      E - Everex SVGA 640x480
  60.      F - Trident SVGA 640x480
  61.      G - VESA Standard SVGA 640x400, 640x480, 800x600, 1024x768, 1280x1024
  62.  
  63.      H - N reserved, unassigned (S)VGA adapter types
  64.  
  65.      O - TIGA/Hercules Graphics Workstation 16-bit
  66.      P - TIGA/Hercules Graphics Workstation 24-bit
  67.  
  68.      Q - Z reserved, unassigned True-Color adapter types
  69.  
  70.    Supported Palette Options:
  71.  
  72.      0 - (default) HSV->RGB method
  73.      3 - 3-3-2 RGB method
  74.      G - Grey Scale (optimized 64-shade palette for IBM PC's)
  75.      H - Sierra High Color pallete DAC
  76.  
  77.  
  78. TEXTURES
  79. -------- 
  80.  
  81. We don't have documentation for ONION & LEOPARD yet, but their syntax
  82. is the same as GRANITE or MARBLE. They do require a COLOR_MAP.
  83. Try them out.
  84.  
  85.  
  86. MAPTYPE - Works with imagemap, bumpmap and material map.
  87. New stuff is a set of new image projection types.  To specify an
  88. imagemap, an additional parameter is optional, i.e.
  89.  
  90.    IMAGEMAP MAPTYPE 1 GIF "xxx.gif" END_MAP
  91.  
  92. Gives a spherical image map.  The types of imagemaps that are now
  93. defined are:
  94.  
  95.    0) (default) Planar map - this is the one that was already there.
  96.    
  97.    1) Spherical map - wraps the image around a sphere.
  98.    2) Cylindrical map - wraps the image around a cylinder (works good for
  99.       hyperboloids, cones, and paraboloids too).
  100.    5) Torus map - wraps the image around a torus.  For this map you need
  101.       to put the major radius of the torus into the first parameter of the
  102.       gradient vector.
  103.  
  104.    3-4) Parabolic and Hyperbolic maps - these are not implemented yet, but
  105.       will be tailored for mapping to the respective types.  The reason for
  106.       having these in addition to the cylindrical types is that these shapes
  107.       deflect differently than a cylinder.    
  108.    
  109.    NOTE: Gradient only effects planar mapping.
  110.  
  111. For all of these image mappers it is assumed that the imagemap will work
  112. in the interval 0 <= Y <= 1.  This means that you need to use the shapes:
  113. QUADRIC QSphere, QUADRIC Cylinder_Y, QUADRIC Hyperbola_Y, etc.  If the default
  114. Planar mapping is used, no object dimensions or coordinates need be changed.
  115.  
  116. See the file "mapper.dat" and the associated gif file "mapper0.gif" for an
  117. example of how the new various types of mappers work.  This file wraps the
  118. picture "rough.gif" around various shapes.
  119.  
  120.  
  121. KEYWORD: MATERIAL_MAP
  122.  
  123. BRIEFLY:
  124.  MATERIAL_MAP maps textures onto an object indexed via a bit-mapped image.
  125.  
  126. SYNTAX:
  127.  MATERIAL_MAP <orientation> Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
  128.   (MAPTYPE #)
  129.   TEXTURE ... END_TEXTURE
  130.   TEXTURE ... END_TEXTURE
  131.   (up to 256 textures)  
  132.  
  133.  END_MATERIAL_MAP 
  134.  
  135. DESCRIPTION:
  136.   MATERIAL_MAP is a lot like IMAGE_MAP. Image map takes a picture and 
  137.   projects it onto an image. Like gluing a picture onto a sphere. Material
  138.   map does the same, but instead of changing the color of the sphere it 
  139.   actually changes the texture of the sphere based on the color in the image.
  140.   When it finds a point that would have color number 0 projected on it, it
  141.   changes that point to the first texture in the MATERIAL_MAP definition. 
  142.   Color index number 1 will become texture number 2 and so on.
  143.  
  144. EXAMPLE:
  145.  OBJECT
  146.    SPHERE <0.0  25.0  0.0>  50.0 END_SPHERE
  147.  
  148.    TEXTURE        { X-Y oriented bitmap image }
  149.     MATERIAL_MAP <1.0 -1.0 0.0> GIF "pvmap.gif" 
  150.     
  151.       TEXTURE 
  152.        COLOR Yellow       
  153.        SPECULAR 0.75
  154.        SCALE <7.0 1.5 3.0> 
  155.       END_TEXTURE
  156.       TEXTURE
  157.        Mirror      
  158.        SPECULAR 0.75
  159.       END_TEXTURE
  160.       TEXTURE
  161.        Dark_Wood
  162.        SPECULAR 0.75
  163.       END_TEXTURE
  164.       TEXTURE
  165.         Jade
  166.         SPECULAR 0.75 
  167.       END_TEXTURE
  168.      
  169.      END_MATERIAL_MAP
  170.      ROTATE <0.0 35.0 0.0>
  171.      SCALE < 15.0 15.0 15.0 >   
  172.    END_TEXTURE
  173. END_OBJECT
  174.  
  175.  
  176. KEYWORD: BUMPMAP
  177.  
  178. BRIEFLY:
  179.  BUMPMAP maps surface "bumps" onto an object indexed via a bit-mapped image.
  180.  
  181. SYNTAX:
  182.  BUMPMAP (<orientation>) Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
  183.  (BUMPSIZE Height or Depth) (USE_COLOR) (USE_INDEX)
  184.  (INTERPOLATE 2 or 4)
  185.  (MAPTYPE #)
  186.  END_MAP
  187.  
  188. DESCRIPTION:
  189.   BUMPMAP is a lot like IMAGEMAP.  IMAGEMAP takes a picture and projects it
  190.   onto an image, like gluing a picture onto a sphere.  BUMPMAP does the same,
  191.   but instead of changing the color of the sphere it actually changes the
  192.   orientation of the surface normal based on the colors in the image.
  193.   When it finds a point that would have color number 0 projected on it, it
  194.   leaves that point's surface normal alone.  Color index number 1 will become
  195.   "bumped" out from the flat surface, color number 2 further still, and so on.
  196.   Try using one of FRACTINT's continuous potential fractals for interesting
  197.   BUMPMAP effects! BUMPSIZE can be negative. Try USE_COLOUR and INTERPOLATION.
  198.  
  199. EXAMPLE:
  200.  OBJECT
  201.    SPHERE <0.0  25.0  0.0>  50.0 END_SPHERE
  202.  
  203.    TEXTURE        { X-Y oriented bitmap image }
  204.       BUMPMAP <1.0 -1.0 0.0> GIF "bumpy.gif"
  205.       BUMPSIZE 3.0  {Try values from negative to very high }
  206.       INTERPOLATE 2
  207.       END_MAP
  208.       AMBIENT 0.2
  209.       DIFFUSE 0.8
  210.       SPECULAR 1.0
  211.    END_TEXTURE
  212.  
  213.    ROTATE <0.0 35.0 0.0>
  214.    SCALE < 15.0 15.0 15.0 >
  215.    END_TEXTURE
  216. END_OBJECT
  217.  
  218.  
  219. KEYWORD: GOUGEMAP
  220.  
  221. BRIEFLY:
  222.  GOUGEMAP maps indentations into an object indexed via a bit-mapped image.
  223.  
  224. SYNTAX:
  225.  GOUGEMAP <orientation> Image-Type "imagefilename" (ONCE) (TURBULENCE 0.0)
  226.  (GOUGESIZE Depth or BUMPSIZE Depth )
  227.  END_MAP
  228.  
  229. DESCRIPTION:
  230.   GOUGEMAP is a lot like IMAGEMAP.  IMAGEMAP takes a picture and projects it
  231.   onto an image, like gluing a picture onto a sphere.  GOUGEMAP does the same,
  232.   but instead of changing the color of the sphere it actually changes the
  233.   orientation of the surface normal based on the colors in the image.
  234.   When it finds a point that would have color number 0 projected on it, it
  235.   leaves that point's surface normal alone.  Color index number 1 will become
  236.   indented from the flat surface, color number 2 further still, and so on.
  237.   GOUGEMAP uses a failed BUMPMAP code that some of us thought produced an
  238.   interesting effect. It may or may not be in the final version.
  239.  
  240. EXAMPLE:
  241.  OBJECT
  242.    SPHERE <0.0  25.0  0.0>  50.0 END_SPHERE
  243.  
  244.    TEXTURE        { X-Y oriented bitmap image }
  245.       GOUGEMAP <1.0 -1.0 0.0> GIF "scratchy.gif"
  246.       GOUGESIZE 1.0  {typ. between 0 and 1.  Try > 1 for really deep gouges }
  247.       AMBIENT 0.3
  248.       DIFFUSE 0.7
  249.       PHONG 1.0
  250.    END_TEXTURE
  251.  
  252.    ROTATE <0.0 35.0 0.0>
  253.    SCALE < 15.0 15.0 15.0 >
  254.    END_TEXTURE
  255. END_OBJECT
  256.  
  257.  
  258.  
  259. POLYNOMIAL SURFACES
  260. -------------------
  261.  
  262. Polynomials of arbitrary degree are handled by one of the following
  263. declarations:
  264.  
  265.    CUBIC < 10 Coefficients > END_CUBIC,
  266.  
  267.    QUARTIC < 35 Coefficients > END_QUARTIC,
  268.  
  269.    POLY < Max-Degree > < (n+1)*(n+2)*(n+3)/6 Coefficients > END_POLY
  270.  
  271. Quartics are the only case handled as a seperate case, with code to solve
  272. them specifically.  Higher order polynomial surfaces are solved using
  273. Sturmian sequences.  (The root solver is based on code from "Graphics Gems"
  274. by Glassner, and is not debugged.  Use at your own risk for surfaces of
  275. degree higher than 4.)  Cubics and quartics seem to be safe - the code for
  276. these surfaces is the same as previous versions and suffers only from
  277. precisions problems leading to digital noise.
  278.  
  279. See "SINSURF.DAT" for a 6th order surface.  So far I haven't gotten a good
  280. render of it as a result of system crashes and too much time spent working
  281. on bicubic patches.
  282.  
  283.  
  284. CLIPPING
  285. --------
  286.  
  287. The keywords CLIPPED_BY and END_CLIP have been added to allow for chopping
  288. parts of a surface by another surface.  The effect is identical to an
  289. INTERSECTION with a transparent surface, but quite a bit faster.  See
  290. "GRAFBIC.DAT" for a Bicorn that has had its front and back chopped.
  291.  
  292.  
  293. BICUBIC PATCHES
  294. ---------------
  295.  
  296. Bicubic patches are a mesh of control points that describe the shape of
  297. a surface.  There are several types of bicubic patches, however the only
  298. one currently understood is the Bezier patch.
  299.  
  300. Bezier patches are bicubic patches that take on the values of the corner
  301. vertices of the mesh, and are influenced by the other values.  A notable
  302. computer graphic object that has this sort of patch definition is the
  303. UTAH Teapot. (See TEAPOT.DAT.)
  304.  
  305. In order to ray-trace a patch, the patch is approximated by a mesh of vertices
  306. that interpolate the patch.  By increasing the number of points in each of
  307. the two mesh parameters (u, and v), a smoother approximation to the true grid
  308. will be traced.  NOTE: Increasing the number of points increases the amount
  309. of work in proportion to U-Resolution * V-Resolution.  If the patch is going
  310. to be small on the screen then you will not need to use a very high resolution.
  311.  
  312. The definition of a BICUBIC patch takes the form:
  313.  
  314.    BICUBIC_PATCH <Patch Type> <U resolution> <V resolution>
  315.       < vertex (0,0) > < vertex (0,1) > < vertex (0,2) > < vertex (0,3) >
  316.       < vertex (1,0) > < vertex (1,1) > < vertex (1,2) > < vertex (1,3) >
  317.       < vertex (2,0) > < vertex (2,1) > < vertex (2,2) > < vertex (2,3) >
  318.       < vertex (3,0) > < vertex (3,1) > < vertex (3,2) > < vertex (3,3) >
  319.  
  320.       [ <texture>, <translate>, <rotate>, ... ]
  321.    END_BICUBIC
  322.  
  323. The value of "Patch Type" determines the shading characteristics of the
  324. patch, and the amount of storage used for mesh constants.  There are
  325. currently three allowed values for "Patch Type":
  326.  
  327.  
  328.    0) Bezier patch, only sufficient storage is allocated to store the tri-
  329.       angular vertices.
  330.  
  331.    1) Bezier patch, vertices, all plane equations defined by the triangulation
  332.       of the patch into subpatches are stored.
  333.  
  334.    2) Bezier patch, using binary subdivision to find the point of surface
  335.       intersection.
  336.  
  337.    3) Bezier patch, using binary subdivision, with vertices and all values
  338.       precomputed and stored.
  339.  
  340.    4) Bezier patch, vertices, all plane equations, normals at each vertex of
  341.       a subpatch are stored (to be used for a SMOOTH_TRIANGLE shading in each
  342.       of subpatch).
  343.  
  344. At some future date, other types of patches besides Bezier may be used.  In
  345. this case new values of Patch Type will be defined for them.
  346.  
  347. The value of "U Resolution" determines the number of steps along the
  348. U parameter (row variable) that are taken when subdividing the patch.
  349.  
  350. The value of "V Resolution" determines the number of steps along the
  351. V parameter (column variable) that are taken when subdividing the patch. 
  352.  
  353. An example of a Bezier patch is:
  354.  
  355.    BICUBIC_PATCH 1 4 4
  356.       < 0.0  0.0  2.0>  < 1.0  0.0  0.0>  < 2.0  0.0  0.0>  < 3.0  0.0 -2.0>
  357.       < 0.0  1.0  0.0>  < 1.0  1.0  0.0>  < 2.0  1.0  0.0>  < 3.0  1.0  0.0>
  358.       < 0.0  2.0  0.0>  < 1.0  2.0  0.0>  < 2.0  2.0  0.0>  < 3.0  2.0  0.0>
  359.       < 0.0  3.0  2.0>  < 1.0  3.0  0.0>  < 2.0  3.0  0.0>  < 3.0  3.0 -2.0>
  360.    END_BICUBIC
  361.  
  362. This is a patch that is interpolated by a 4x4 mesh of vertices.  This is
  363. subdivided into 2x4x4 = 32 triangles.  This second subdivision into triangles
  364. is algorithmic and occurs in two situatons, when the patch is parsed and when
  365. intersections are being calculated.  In addition the plane equation of all
  366. 32 triangles are stored so that intersection calculations can be optimized
  367. a bit.
  368.  
  369. If the Patch Type were changed from 1 to 3, normal calculations based on the
  370. normal to the patch at each of the mesh vertices would be used.  This gives
  371. the same shading effect that SMOOTH_TRIANGLE's have.
  372.  
  373. For example, the following patch definition has taken 16 co-planar points
  374. arranged in the grid 0 <= x <= 1 && 0 <= y <= 1 && z = 0, and pulled two
  375. corners down and two corners up along the z-axis. (See BEZIER.DAT.)
  376.  
  377. OBJECT
  378.    BICUBIC_PATCH 1 4 4
  379.       < 0.0  0.0  2.0>  < 1.0  0.0  0.0>  < 2.0  0.0  0.0>  < 3.0  0.0 -2.0>
  380.       < 0.0  1.0  0.0>  < 1.0  1.0  0.0>  < 2.0  1.0  0.0>  < 3.0  1.0  0.0>
  381.       < 0.0  2.0  0.0>  < 1.0  2.0  0.0>  < 2.0  2.0  0.0>  < 3.0  2.0  0.0>
  382.       < 0.0  3.0  2.0>  < 1.0  3.0  0.0>  < 2.0  3.0  0.0>  < 3.0  3.0 -2.0>
  383.       TEXTURE CHECKER COLOR RED 1.0 COLOR BLUE 1.0 ROTATE <90 0 0>
  384.               AMBIENT 0.1 DIFFUSE 0.9 PHONG 1 END_TEXTURE
  385.    END_BICUBIC
  386.    TRANSLATE <-1.5 -1.5 0>
  387.    SCALE <2 2 2>
  388.    ROTATE <30 -70 0>
  389.    BOUNDED_BY SPHERE <0 0 0> 6 END_SPHERE END_BOUND
  390. END_OBJECT
  391.  
  392.  
  393. STURMIAN SEQUENCES
  394. ------------------
  395.  
  396. There have been many improvements in calcluating 3rd and 4th order surfaces.
  397. By default they are still computed the same was as previously, but there is
  398. a new and better way:  Sturmian Sequences! - these seem to cure the majority
  399. of problems with math precision errors resulting in digital acne or outright
  400. noise bursts in the QUARTIC shapes.  The classic error-prone TEARDROP file
  401. now runs beautifully!  This takes care of some of the worst of the problems,
  402. but seems to lead to occasional problems when the normal is calculated (the
  403. surface is correct but the shading is sometimes a little off).  The bad
  404. shading isn't totally random either - it often makes sort of swirl patterns.
  405. In order to use the Sturmian Sequence method, place the keyword STURM anywhere
  406. after the end of the vectors inside a Cubic, Quartic or Bicubic Patch shape
  407. definition.
  408.  
  409. Example:
  410.  
  411. OBJECT
  412.    QUARTIC
  413.    < 1.0   0.0   0.0    0.0     2.0   0.0   0.0   2.0   0.0 -104.0
  414.      0.0   0.0   0.0    0.0     0.0   0.0   0.0   0.0   0.0    0.0
  415.      1.0   0.0   0.0    2.0     0.0  56.0   0.0   0.0   0.0    0.0
  416.      1.0   0.0 -104.0   0.0   784.0 >
  417.    STURM { <-----<<< Must be placed before the END_ statement! <----<<<< }
  418.    END_QUARTIC
  419.    .
  420.    .
  421.    .
  422. END_OBJECT
  423.  
  424.  
  425. DECLARED CONSTANTS
  426. ------------------
  427.  
  428. Here are the various types of constants allowed by the DECLARE statement:
  429.  
  430. OBJECT_CONSTANT
  431. SPHERE_CONSTANT
  432. PLANE_CONSTANT
  433. TRIANGLE_CONSTANT
  434. SMOOTH_TRIANGLE_CONSTANT
  435. QUADRIC_CONSTANT
  436. POLY_CONSTANT (QUARTIC)
  437. POLY_CONSTANT (CUBIC)
  438. POLY_CONSTANT (POLY)
  439. BICUBIC_PATCH_CONSTANT
  440. CSG_INTERSECTION_CONSTANT
  441. CSG_UNION_CONSTANT
  442. CSG_DIFFERENCE_CONSTANT
  443. COMPOSITE_CONSTANT
  444. TEXTURE_CONSTANT
  445. VIEW_POINT_CONSTANT
  446. COLOUR_CONSTANT
  447. VECTOR_CONSTANT
  448. FLOAT_CONSTANT
  449.  
  450. Smile - 
  451.  
  452. If you cannot afford a texture block, a default one will be appointed to you!
  453.